	<div id="preamble">
          <h3>Terms</h3>
    <ul>
          <li><b>Physical:</b>
	<br>
	A "physical" (phys) represents an entity capable of receiving a request.
    Physicals make up the pool of resources available to farms. Usually this just means
    a machine with a http server on it, although there could be more than one on a machine
    differentiated by port. Statistics are updated for each physical.
	  </li>
          <li><b>Farm:</b>
	<br>
    A "farm" represents a collection of physicals that an algorithm can be applied to.
	  </li>
      <li><b>Physical status:</b>
	
		  <ul>
		  <li><code><b>on / off</b></code>
		    Indicates administrative status. If off, not available to farm.
		    Only set manually.
		  </li>
		  <li><code><b>up / down</b></code>
		    Indicates health. If down, not available to farm. Monitoring script
		    will alarm. Only set manually.
		  </li>
		  <li><code><b>in / out</b></code>
		    Indicates health by update frequency. If out, not available to farm.
		    Monitoring script will alarm. Set automatically.
		      See <a href="#AthExpectUpdate">AthExpectUpdate</a>.
		  </li>
		  </ul>
      </li></ul>
	  <h3>Directives</h3>

	  <ul id=toc>
	    <li> <a href="#AthEngine">AthEngine</a></li>
	    <li> <a href="#AthPath">AthPath</a></li>
	    <li> <a href="#AthSHMFile">AthSHMFile</a></li>
	    <li> <a href="#AthMUXPrefix">AthMUXPrefix</a></li>
	    <li> <a href="#AthMUXCount">AthMUXCount</a></li>
	    <li> <a href="#AthAllowMirror">AthAllowMirror</a></li>
	    <li> <a href="#AthAllowDiverseMulti">AthAllowDiverseMulti</a></li>
<!--	    <li> <a href="#AthReadOnlyPolicy">AthReadOnlyPolicy</a></li> -->
	    <li> <a href="#AthFarm">AthFarm</a></li>
	    <li> <a href="#Member"><i>Member</i></a> (Not handled by apache's built-in configurator)</li>
	    <li> <a href="#AthAlgorithm">AthAlgorithm</a></li>
	    <li> <a href="#AthAlgoMaxExcluded">AthAlgoMaxExcluded</a></li>
	    <li> <a href="#AthAlgoHitAdds">AthAlgoHitAdds</a></li>
	    <li> <a href="#AthExpectUpdate">AthExpectUpdate</a></li>
	    <li> <a href="#AthExpectUpdateField">AthExpectUpdateField</a></li>
	    <li> <a href="#AthExpectTTL">AthExpectTTL</a></li>
	    <li> <a href="#AthExpectRecoverTTL">AthExpectRecoverTTL</a></li>
	    <li> <a href="#AthNominationPerUpdate">AthNominationPerUpdate</a></li>
	    <li> <a href="#AthSmartfarmEnable">AthSmartfarmEnable</a></li>
	    <li> <a href="#AthCookieNameSmartfarm">AthCookieNameSmartfarm</a></li>
	    <li> <a href="#AthAllDownURL">AthAllDownURL</a></li>
	    <li> <a href="#AthOfflineURL">AthOfflineURL</a></li>
	    <li> <a href="#AthDefaultPhysOn">AthDefaultPhysOn</a></li>
	    <li> <a href="#AthDefaultFarmOn">AthDefaultFarmOn</a></li>
	    <li> <a href="#AthDefaultPhysStatusFormat">AthDefaultPhysStatusFormat</a></li>
	    <li> <a href="#AthDefaultFarmStatusFormat">AthDefaultFarmStatusFormat</a></li>
	    <li> <a href="#AthDefaultEngineStatusFormat">AthDefaultEngineStatusFormat</a></li>
	  </ul>

	</div>
	
<br>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthEngine"></a><h2>AthEngine</h2>
<table class="directive">
<tr><th>Description:</th><td>Enables / disables request handling by amodule</td></tr>
<tr><th>Syntax:</th><td><code>AthEngine <var>{ On | Off }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthEngine Off</code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>Setting this flag to <var>On</var> allows the mod_athena request handler to 
    process requests. The engine defaults to <var>Off</var>, which bypasses post 
    configuration checks, child init tasks (including shared memory and locks 
    creation), and request handling.
    If the server is initially On by configuration, it will write this status 
    to the engine shared memory object. The request handler checks to make sure 
    BOTH the server conf and the engine object are set to On. However, there is 
    currently no mechanism to update the engine object to turn it off while running.
    It's hard to imagine why you wouldn't just change the directive and 
    send a HUP signal instead, but I can change this if there is a demand.</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthPath"></a><h2>AthPath</h2>
<table class="directive">
<tr><th>Description:</th><td></td></tr>
<tr><th>Syntax:</th><td><code>AthPath <var>local_url_path</var></code></td></tr>
<tr><th>Default:</th><td><code>AthPath /athena</code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>This path is relative to the server's root directory.
    <div class="example">
      <p><code>AthPath /my_athena</code></p>
      <br>
      <p>sets the url for server "my_server" mod_athena engine to:</p>
      <br>
      <p><code>http://myserver/my_athena</code></p>
    </div>
    This is the url used to interact with the mod_athena engine. Requests that match
    this initial string will be intercepted and their handling will end with 
    mod_athena's handler (they will not fall through to mod_proxy).
    The engine's functions are accessed via a directory syntax:
    <div class="example">
      <p>/athena/balance</p>
      <p>/athena/status/farm</p>
      <p>/athena/status/phys</p>
      <p>/athena/status/engine</p>
      <p>/athena/update/farm</p>
      <p>/athena/update/phys</p>
      <p>/athena/mirror/farm</p>
      <p>/athena/mirror/phys</p>
    </div>
    These must always be followed by an appropriate query string.
    Details for these features are found in
    <a href="mod_athena_engine_update.html">Sending statistics</a>,
    <a href="mod_athena_engine_manage.html">Runtime management</a>, and
    <a href="mod_athena_engine_query.html">Querying the balancer</a>
</p>
</div>


<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthSHMFile"></a><h2>AthSHMFile</h2>
<table class="directive">
<tr><th>Description:</th><td>Path used to create and attach shared memory</td></tr>
<tr><th>Syntax:</th><td><code>AthSHMFile <var>file-path</var></code></td></tr>
<tr><th>Default:</th><td><code>AthSHMFile /tmp/.apache_mod_athena_shm</code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>This path may be treated differently by different platforms. It is used by
    the apr shm creation and attachment functions. You should be fine with leaving it
    in /tmp, or setting it to a file in your apache log directory.</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthMUXPrefix"></a><h2>AthMUXPrefix</h2>
<table class="directive">
<tr><th>Description:</th><td>Path prefixed to locks for creation and initialization</td></tr>
<tr><th>Syntax:</th><td><code>AthMUXPrefix <var>file-path</var></code></td></tr>
<tr><th>Default:</th><td><code>AthMUXPrefix /tmp/.apache_mod_athena_mux.</code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
    <p>Used to provide apr lock functions with a path. Same principle as 
      <code>AthSHMPath</code>, except in this case multiple files are created,
      with a corresponding integer index appended. Depending on your platform,
      you may or may not see these files on the filesystem (APR_LOCK_MECH 
      dependent).
    </p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthMUXCount"></a><h2>AthMUXCount</h2>
<table class="directive">
<tr><th>Description:</th><td>Number of locks created to synchronize updates</td></tr>
<tr><th>Syntax:</th><td><code>AthMUXCount <var>integer</var></code></td></tr>
<tr><th>Syntax:</th><td><code>AthMUXCount -1</code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>Depending on your locking mechanism and your kernel limits, this variable may
need to be adjusted. The default <var>-1</var> triggers the engine to try to create
locks for all farms and physicals in the configuration file, plus the engine.
You can explicitly set it to one of ("-1", "row") for the same result.
For file and posix pthread locks, the default should be fine. However on systems where
SYSV semaphores are used, this will most likely be too high (FreeBSD default limit is
10). You can either increase your kernel limits to allow enough semaphores, or set 
<code>AthMUXCount</code> to a lower number like 8 or 4. It must not be less than 3.
When there are fewer locks than objects to be locked, the locks are shared accross 
multiple objects. The ammount of CPU time spent locked is small enough that this
has little impact (at least in installations of less than 50 physicals). 
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthAllowMirror"></a><h2>AthAllowMirror</h2>
<table class="directive">
<tr><th>Description:</th><td>Controls access to mirroring features</td></tr>
<tr><th>Syntax:</th><td><code>AthAllowMirror <var>{ On | Off }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthAllowMirror Off</code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>Set to <var>On</var> to allow requests to <code>/athena/mirror</code> feature.
Be sure to have you security controls thought out before enabling this feature. When 
mirroring, this must be enabled on the <i>secondary</i> engine, not the primary.
By sending serialized farm and physical objects to the mirror application,
one can mirror the complete state of the primary to the secondary.
See <a href="mod_athena_architecture.html">Architectural suggestions</a> for more information.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthAllowDiverseMulti"></a><h2>AthAllowDiverseMulti</h2>
<table class="directive">
<tr><th>Description:</th><td>Enables embedding of different request types in a single request</td></tr>
<tr><th>Syntax:</th><td><code>AthAllowDiverseMulti <var>{ On | Off }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthAllowDiverseMulti Off</code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
    <p>The mod_athena handler can process multiple requests tagged on the 
      end of a normal request using the "&" character.
      An example multiple embedded request looks like this:
    <div class="example">
      <p><code>http://my_server/athena/status/phys/?h=app1&/status/farm/?n=farm1</code></p>
      <br><p>returns something like:</p>
      <br><code><font size=-3>
<p>1060131735041539 (1/1) | 1.000000 | 0.000000 | 0.000000 | 0.000000 | 1.000000 | 0.000000 | 0.014394 &lt;app1&gt; [farm1 farm2]
<br>farm1: (1) algo: simple-cpu  expect update: 1 (chosen: N/A)
<br>&nbsp;&nbsp;&nbsp;down url: http://myserver/down.html
<br>&nbsp;&nbsp;&nbsp;members: app1 app2 app3
      </p></font></code>
    </div>
    in other words, it's handling two requests sequentially, and 
    concatenating their output in a single reponse.
    Normally, for security reasons, you are only allowed to embed 
    multiple requests if they are all for the same engine component 
    as defined by subdirectory, eg. all "/status", "/update", "/mirror", 
    etc. can only be embedded with their own type. 
    <code>AthAllowDiverseMulti</code> allows you to embed different types in the
    same request when set to on, eg. a status and an update together.
    <p>Embedding is a handy way to cut down on network traffic.</p>
</p>
</div>

<!--
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthReadOnlyPolicy"></a><h2>AthReadOnlyPolicy</h2>
<table class="directive">
<tr><th>Description:</th><td>Controls read / write access to internal data</td></tr>
<tr><th>Syntax:</th><td><code>AthReadOnlyPolicy <var>{ none | strict }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthReadOnlyPolicy none</code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>POSSIBLE FUTURE DEPRECATION. 
This feature is of questionable value, since the security it provides
can also be implemented with good apache configuration in a single daemon.
Using this setting, you can take advantage of shared memory by starting one 
instance of apache (with the policy set to <code>none</code>) to handle all updates
listening on a secure interface, then starting another httpd 
in <code>strict</code> mode listening on the external interface.
This second instance will be able to load balance requests, but will not
be able to change any statistics or status of anything.
Note that the <code>strict</code> instance will not be able to implement certain
engine features, and it will error out on startup on the directives that
make no sense.
</p>
</div>
-->

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthFarm"></a><h2>AthFarm</h2>
<table class="directive">
<tr><th>Description:</th><td>A collection of physicals into one entity for balancing</td></tr>
<tr><th>Syntax:</th><td><code>AthFarm <var>name*</var></code></td></tr>
<tr><th></th><td><font size=-3>*Restricted to lower case, single word. Multiple declarations allowed.</font></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>This is how a farm is declared. A farm contains 
( 0 &lt;= x &lt;= AthPhysicalsMax ) members.
This works more or less like a standard apache directory declaration
in that certain directives can appear inside the farm declaration
and apply to that only that farm. The <a href="#Member">Member</a>
directive can only appear inside a farm. 
The others can appear in server config context, where they 
become the defaults for all farms unless overriden in the farm 
declaration. The membership and some settings of the farm can also
be managed while the server is running using update requests.
An example farm:
<div class="example">
      <code>
	&lt;AthFarm farm-one&gt;
	<br>&nbsp;&nbsp;AthExpectUpdate On
	<br>&nbsp;&nbsp;AthAlgorithm simple-cpu
	<br>&nbsp;&nbsp;Member server-1
	<br>&nbsp;&nbsp;Member server-2
	<br>&nbsp;&nbsp;Member server-3
	<br>&lt;/AthFarm&gt;
      </code>
</div>
Because of the way mod_proxy and/or httpd processes the host component
of the url in the request (it gets canonicallized)
before mod_athena's handler gets it, but after mod_proxy rewrites it,
farm names must be like hostnames in their canonicallized form.
The simplest way to accomplish this is to just use lower case, single word farm names.
I may make my farm name matching also perform canonicalization in the future, but this
is the cleanest and simplest solution.
</p>
<p>
There can be up to AthFarmsMax declarations of unique farms.
As the mod_athena config handler parses the farms, it generates
a list of unique Members (physicals). This then becomes the list
of available physicals to be moved around between farms or on which
to update statistics. For this reason, you may find it useful to always
have one farm that is not used, but contains all your servers. You
will not be wasting memory by doing this.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="Member"></a><h2>Member</h2>
<table class="directive">
<tr><th>Description:</th><td>A server available to a farm</td></tr>
<tr><th>Syntax:</th><td><code>Member <var>hostname [ On | Off ]</var></code></td></tr>
<tr><th>Context:</th><td>AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>This directive only works inside an AthFarm declaration.
It declares <var>hostname</var> as a <i>physical</i>, if it has
not already been declared in a previous farm, and adds it to the list
of members of the current farm. The hostname can be followed optionally
by a flag <var>On</var> or <var>Off</var> to set its initial 
administrative status as online or offline. 
If this is not provided, it defaults
to the value of <a href="#AthDefaultPhysOn">AthDefaultPhysOn</a>.
</p>
<p>The configuration handler performs no validation of <var>hostname</var>.
This will be up to mod_proxy to deal with.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthAlgorithm"></a><h2>AthAlgorithm</h2>
<table class="directive">
<tr><th>Description:</th><td>A string that describes an algorithm to be used</td></tr>
<tr><th>Syntax:</th><td><code>AthAlgorithm <var>{ r | s-c ... | d-c-n-2 ... }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthAlgorithm round-robin</code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Overrides:</th><td>AthFarm over server</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>In server context, this sets the algorithm to be used for all farms 
who do not override it with an additional <code>AthAlgorithm</code> 
directive. An algorithm string is built by joining the type to the
modifiers with a "-". In all cases a word can substituted by its 
initial letter. Here is the list of algorithm words:
<div class="example">
<code>
<b>types:</b>
<br>&nbsp;&nbsp;round-robin
<br>&nbsp;&nbsp;simple
<br>&nbsp;&nbsp;dynamic
<br><b>modifiers:</b>
<br>&nbsp;&nbsp;cpu, net, mem, ld, disk
<br>&nbsp;&nbsp;0cus, 1cus, 2cus, ..., 9cus
</code>
</div>
<p>Modifiers 
<code>0cus, 1cus, 2cus, </code> are meant to be used for custom
variables, but you can store any float you want in any of the fields
and then use them how you want, disregarding the convention of the
field names. No algorithm logic is tied to a field's name.
</p>
<p>Type <code>round-robin</code> ignores all modifiers.
It causes each request to be passed to the next physical in the
member list of the farm, looping to the begin after the list end.
</p>
<p>Type <code>simple</code> accepts a single modifier, eg.
<code>simple-cpu</code>. If no modifier is provided it defaults
to cpu. It will then always pick the machine with the lowest value
in this field (these are floats in C, eg -0.5 &lt; 0.1), and if there
are more than one at the lowest value, it will end up grabbing the
first in the list of this group of best candidates. In other words,
if the same three physicals are at cpu value 0.0, it will pick the 
same one of those three each time this happens. This behavior can be modified
with the <a href="#AthAlgoHitAdds">AthAlgoHitAdds</a> directive. Pay attention to 
this issue, because if your hit rate is much higher than your update frequency,
then you can really beat up a physical.

</p>
Type <code>dynamic</code> accepts any subset of the modifiers,
eg. <code>dynamic-cpu-mem-1cus-2cus</code>.
This algorithm is a bit complicated, but still very fast.
First, it traverses all members of the farm, finding the minimum and 
maximum values of the first field to be used, in our example, "cpu".
Then, it uses this to calculate a new value for this field 
for each member farm, weighting it between 0 (the min) and 1 (the max).
It repeats this for every requested field.
</p>
<p>
Next, for each member of the farm, the weighted values of every requested
field are added together. It then chooses the member with the lowest value
of summed weighted fields. 
</p>
<p>Use this if you have a number of fields that matter when making load 
balancing decisions. Handily, it automatically places the highest influence
on the field with most variability. If min and max are close together, or if
most members are close to any particular value, their weighted values
will have little (universally equal) affect on the summed total.
For instance, in our example, if mem is maxed on all members, the custom
values are close to zero, but cpu is inconsistent, then cpu will
affect the decision most.
</p>
<p>There is a side affect of this algorithm
you may wish to prevent. It could be that a server has maxed out in 
a particular field, eg. cpu, that prevents it from doing much else,
which then pushes the other fields close to zero. In this case
it is likely that it will have the lowest summed weighted value.
However, this field being maxed makes it a very bad candidate.
You can prevent the algorithm from chosing a server in this 
situation by setting <a href="#AthAlgoMaxExcluded">AthAlgoMaxExcluded</a>.
With this set to <var>On</var>, the server will rule out members
who have a weighted field equal to 1 (a maximum) in any of the
specified fields, as long as another is available. If every machine
matches this condition, then it falls back to the lowest value.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthAlgoMaxExcluded"></a><h2>AthAlgoMaxExcluded</h2>
<table class="directive">
<tr><th>Description:</th><td>Tunes the "dynamic" algorithm</td></tr>
<tr><th>Syntax:</th><td><code><var>{On | Off} </var></code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>
See above <a href="#AthAlgorithm">AthAlgorithm</a> (dynamic algorithm detail).
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthAlgoHitAdds"></a><h2>AthAlgoHitAdds</h2>
<table class="directive">
<tr><th>Description:</th><td>A value added to a field concurrent with a reverse proxy request</td></tr>
<tr><th>Syntax:</th><td><code>AthAlgoHitAdds <var>{ OFF | cpu | net | mem | ld | 0cus | 1cus | 2cus ... 9cus } float</var></code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>When a request comes through that is handled by mod_proxy as a reverse proxy 
request, and is targeted for load balancing, it becomes a candidate for this rule.
If the first argument is set to a valid field type
in the current farm, it will follow through with the "hit adds" logic for the
specified field. After the farm's algorithm picks a physical, its matching field will
be incremented by <code>float</code>.
There can be only one field per farm that is affected by this rule.
Before the request is handed back to mod_proxy for completion, the value
of the specified field is incremented by <code>AthAlgoHitAdds</code>.
</p>
<p>
This is probably most useful in very large installations, and/or when the
field statistics updates are infrequent for relevant members. 
For example, if you know a hit 
to a particular farm always results in the dramatic increase in a particular
field, but you are not likely to get new statistics for that field before
the next request comes in, you might want to use this. It will prevent
a request that comes in before new stats are available from being sent 
to the member we already know is doing something (its field is inflated
artificially by the value of <var>float</var>). 
As soon as new statistics are sent in, its affect is erased.
</p>
<p><b>NOTE:</b> Further experience has proven this to be an indispensible tuning
for most installations. Specifically, if you are serving multi-frame pages or pages
with images, then any instantaneous "page" request actually represents many hits, and you
want these to be load balanced, despite the impossibility of having instantaneous knowledge
of the load on target servers. I've used a setting "cpu .01" to great advantage.
</p> 
<p>If you have a server context setting for this rule, but want to cancel its
affects on a farm, just set the field name to anything but a valid one
(eg. OFF) and/or set the <var>float</var> value to zero.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthExpectUpdate"></a><h2>AthExpectUpdate</h2>
<table class="directive">
<tr><th>Description:</th><td>Expect a physical statistic update within a certain amount of time</td></tr>
<tr><th>Syntax:</th><td><code>AthExpectUpdate <var>{ On | Off }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthExpectUpdate Off</code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>
When this directive is set to <var>On</var>, mod_athena will expect to
get new statistics for a field specified by
<a href="#AthExpectUpdateField">AthExpectUpdateField</a> within every
<a href="#AthExpectTTL">AthExpectTTL</a> seconds for each member (physical)
in the relevant farm.
If it does not, it will set the physical to be timed <code>out</code>, and 
it will not be availale to be chosen by an algorithm <b>in any farm</b>.
Physical status is managed in shared memory context, not in farm-specific context.
If the engine begins receiving updates again, and 
<a href="#AthExpectRecoverTTL">AthExpectRecoverTTL</a> 
is set to a non-zero value, it will mark the physical <code>up</code>
after that number of seconds has passed since being marked out. This
allows your server to recover gracefully.
</p>
<p>It is critical to understand the context of this rule, 
because it has serious side affects.
If you have the same physical as a member in two farms, but the farms have
different settings for AthExpect..., failure in any of the rules
will cause it to be marked out and be unavailable in all the farms in which
that physical is a member. But... read on:
</p>
<p>This rule is run only when an algorithm is run for a farm
in which this rule is active. No physical will get marked out if no request
is made to the farm, even if the TTL has expired. Also, if every physical
has expired in a farm, and no request has ever been made to the farm, then
the first request that does come will fail (or be sent the 
<a href="#AthAllDownUrl">all</a> down url). In low traffic environments, you
can work around this problem by scripting a periodic call to balance the farm,
either by hitting a url in the farm or by using the mod_athena balance query
engine. This will force the rule check, and you will be alerted to failure
more quickly (if you are monitoring it).
In moderate or high traffic environments, it is not an issue.
More details about using this feature, as well as work-arounds for the scope
of physical status, are in the 
<a href="mod_athena_architecture.html">Architectural suggestions</a> section.
</p>

</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthExpectUpdateField"></a><h2>AthExpectUpdateField</h2>
<table class="directive">
<tr><th>Description:</th><td>The field checked for updates</td></tr>
<tr><th>Syntax:</th><td><code>AthExpectUpdateField <var>{ cpu | net | mem | ld | 0cus | 1cus ... 9cus }</var></code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>See <a href="#AthExpectUpdate">AthExpectUpdate</a> for details.</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthExpectTTL"></a><h2>AthExpectTTL</h2>
<table class="directive">
<tr><th>Description:</th><td>The number seconds to wait for new statistics from a member</td></tr>
<tr><th>Syntax:</th><td><code>AthExpectTTL <var>integer, seconds</var></code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>See <a href="#AthExpectUpdate">AthExpectUpdate</a> for details.</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthExpectRecoverTTL"></a><h2>AthExpectRecoverTTL</h2>
<table class="directive">
<tr><th>Description:</th><td>The number of seconds to wait before re-enabling a member</td></tr>
<tr><th>Syntax:</th><td><code>AthExpectRecoverTTL <var>integer, seconds</var></code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>See <a href="#AthExpectUpdate">AthExpectUpdate</a> for details.</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthNominationPerUpdate"></a><h2>AthNominationPerUpdate</h2>
<table class="directive">
<tr><th>Description:</th><td></td></tr>
<tr><th>Syntax:</th><td><code>AthNominationPerUpdate <var>{ On | Off }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthNominationPerUpdate Off</code></td></tr>
<tr><th>Context:</th><td>server</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>If you find that you are serving SO MANY requests per second that
calculating choices slows you down-- wait that's absurd, just rediculous.
</p>
<p>Anyway. Setting this causes the engine to choose a server each time
statistics are updated. When a request comes in to update the stats
for a physical, the engine looks up each farm it is in and runs the 
appropriate algorithm for the farm, and stores the result in each farm.</p>
<p>Then, when a reverse proxy request comes in for a farm, it checks the
stored value, which will contain the best choice from the latest 
statistics, and use that. No calculation is performed.
<p>Basically, this switches from per-request to per-update balancing.
</p>
</div>


<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthSmartfarmEnable"></a><h2>AthSmartfarmEnable</h2>
<table class="directive">
<tr><th>Description:</th><td></td></tr>
<tr><th>Syntax:</th><td><code>AthSmartfarmEnable <var>{ On | Off }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthSmartfarmEnable Off</code></td></tr>
<tr><th>Context:</th><td>server</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>Enabling this feature causes the engine to inspect requests for the cookie
named in <a href="#AthCookieNameSmartfarm">AthCookieNameSmartfarm</a>, and
to then handle whatever manipulation is requested in it.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthCookieNameSmartfarm"></a><h2>AthCookieNameSmartfarm</h2>
<table class="directive">
<tr><th>Description:</th><td></td></tr>
<tr><th>Syntax:</th><td><code>AthCookieNameSmartfarm <var>cookie name</var></code></td></tr>
<tr><th>Default:</th><td><code>AthCookieNameSmartfarm X-Ath-Smartfarm</code></td></tr>
<tr><th>Context:</th><td>server</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>Sets the name of the cookie that triggers smartfarm handling.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthAllDownURL"></a><h2>AthAllDownURL</h2>
<table class="directive">
<tr><th>Description:</th><td>Url to forward to when all farm members are <code>down</code></td></tr>
<tr><th>Syntax:</th><td><code>AthAllDownURL <var>full/url</var></code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>When a request goes to a farm in which all members have been marked <code>down</code>
OR <code>offline</code> this URL will be provided.</p>
<p>If the target farm is itself marked <code>offline</code> then no member checks are 
done and no algorithm is run. The request is immediately returned the
<a href="#AthOfflineURL">AthOfflineUrl</a>.</p>

<p>This allows you to distinguish between being <code>down</code>, a condition of
system failure, and being <code>offline</code>, an administrative status.
The status of <code>down</code> only applies to a physical member, since that
is what determines system health. The status of <code>offline</code> applies
to both farms and physicals.</p>
<p>Be aware that if a farm is NOT <code>offline</code> but all its member
physicals are <code>offline</code>, then the AthAllDownURL is returned.
This may seem odd, but since the facility to mark the farm itself offline exists
there is no need to complicate mod_athena's code. If this bothers you, you can 
always write a script that checks if every member of a farm is marked offline, and
then mark that farm offline.</p>
<p>The ability to mark physicals <code>offline</code> is provided primarily to
allow for intelligent monitoring. You probably only want to be alerted when a
machine fails unintentionally, eg. <code>down</code>, not when it's being restarted
or upgraded or under some other non-failure maintenance. The mod_athena script
"ath_monitor.sh" does exactly this-- it will ignore <code>offline</code> physicals.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthOfflineURL"></a><h2>AthOfflineURL</h2>
<table class="directive">
<tr><th>Description:</th><td>Url to forward to when all farm members are <code>offline</code></td></tr>
<tr><th>Syntax:</th><td><code>AthOfflineURL <var>full/url</var></code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
See <a href="#AthAllDownURL">AthAllDownUrl</a> for details.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthDefaultPhysOn"></a><h2>AthDefaultPhysOn</h2>
<table class="directive">
<tr><th>Description:</th><td>Sets the initial adminstrative state of physicals (members)</td></tr>
<tr><th>Syntax:</th><td><code>AthDefaultPhysOn <var>{ On | Off }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthDefaultPhysOn On</code></td></tr>
<tr><th>Context:</th><td>server, AthFarm config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>If a <a href="#Member">Member</a> directive does not include its own 
<var>On / Off</var> flag, this becomes the initial state set for the physical
as either <code>online</code> or <code>offline</code>.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthDefaultFarmOn"></a><h2>AthDefaultFarmOn</h2>
<table class="directive">
<tr><th>Description:</th><td>Sets the initial adminstrative state of farms</td></tr>
<tr><th>Syntax:</th><td><code>AthDefaultFarmOn <var>{ On | Off }</var></code></td></tr>
<tr><th>Default:</th><td><code>AthDefaultFarmOn On</code></td></tr>
<tr><th>Context:</th><td>sever config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>This is the initial state for all farms, either 
<code>online</code> or <code>offline</code>. 
There is no per-farm status setting on start-up provided.
</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthDefaultPhysStatusFormat"></a><h2>AthDefaultPhysStatusFormat</h2>
<table class="directive">
<tr><th>Description:</th><td>Sets the format string for status/phys requests</td></tr>
<tr><th>Syntax:</th><td><code>AthDefaultPhysStatusFormat <var>format string</var></code></td></tr>
<tr><th>Default:</th><td><code>AthDefaultPhysStatusFormat 
<font size=-3><pre>"%t (%o/%u) | %c | %n | %l | %m | %0 | %1 | %2 | %3 | %4 | %5 | %6 | %7 | %8 | %9 <%h> [%f]"</pre></font></code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>This is the format used for requests for physical status, when no format is specified.
See <a href="mod_athena_engine_manage.html">Runtime management</a> for format 
codes. In the conf file, these should be single line strings.</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthDefaultFarmStatusFormat"></a><h2>AthDefaultFarmStatusFormat</h2>
<table class="directive">
<tr><th>Description:</th><td></td></tr>
<tr><th>Syntax:</th><td><code>AthDefaultFarmStatusFormat <var>format string</var></code></td></tr>
<tr><th>Default:</th><td><code>AthDefaultFarmStatusFormat 
<font size=-3><pre>"%n: (%o) algo: %a %h expect update: %e (chosen: %c)\n
   down url: %d offline url: %D\n
   members: %m\n"</pre></font></code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>This is the format used for requests for farm status, when no format is specified.
See <a href="mod_athena_engine_manage.html">Runtime management</a> for format 
codes. In the conf file, these should be single line strings.</p>
</div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section">
<a name="AthDefaultEngineStatusFormat"></a><h2>AthDefaultEngineStatusFormat</h2>
<table class="directive">
<tr><th>Description:</th><td></td></tr>
<tr><th>Syntax:</th><td><code>AthDefaultEngineStatusFormat <var>format string</var></code></td></tr>
<tr><th>Default:</th><td><code>AthDefaultEngineStatusFormat 
<font size=-3><pre>"path: %P down url: %d farms: %f physicals: %p nominate per update (0/1): %n\n
defaults for farms:\n
   algorithm: %a %h\n
   expect update: %e\n
   ttl: %t"</pre></font></code></td></tr>
<tr><th>Context:</th><td>server config</td></tr>
<tr><th>Status:</th><td>Extension</td></tr>
<tr><th>Module:</th><td>mod_athena</td></tr>
</table>
<p>This is the format used for requests for engine status, when no format is specified.
See <a href="mod_athena_engine_manage.html">Runtime management</a> for format 
codes. In the conf file, these should be single line strings.</p>
</div>

